-
Notifications
You must be signed in to change notification settings - Fork 10.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve the JSDoc comments #11235
Improve the JSDoc comments #11235
Conversation
/botio-linux preview |
/botio-linux preview |
Another thing I just noticed is that |
Yes, this is because the closure is called |
Given Lines 146 to 147 in 4af2755
Lines 1593 to 1596 in 4af2755
|
Sometimes we also used `Number` and `integer`, but `number` is what the JSDoc documentation recommends.
Sometimes we also used `String`, but `string` is the what the JSDoc documentation recommends.
…ments Square brackets are recommended to indicate optional parameters. Using them helps for automatically generating correct documentation.
Sometimes we also used `@return` or `@returns`, but `@type` is what the JSDoc documentation recommends. This also improves the documentation because before this commit the types were not shown and now they are.
Sometimes we also used `@return`, but `@returns` is what the JSDoc documentation recommends. Even though `@return` works as an alias, it's good to use the recommended syntax and to be consistent within the project.
243bf5d
to
5ee5caa
Compare
/botio-linux preview |
From: Bot.io (Linux m4)ReceivedCommand cmd_preview from @timvandermeij received. Current queue size: 0 Live output at: http://54.67.70.0:8877/15dd7d913e2aab9/output.txt |
From: Bot.io (Linux m4)SuccessFull output at http://54.67.70.0:8877/15dd7d913e2aab9/output.txt Total script time: 1.63 mins Published |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks fine by me, modulo one small last comment; thanks!
…rker` Both classes live inside a closure with the same name, which confuses JSDoc. Move the documentation to the inner class to deduplicate them.
This file only contains helper functions and should not be listed in the documentation since they are not part of the public API.
This commit allows JSDoc to generate all API documentation in the `pdfjsLib` module (namespace) so the documentation becomes easier to navigate.
This commit series makes our JSDoc comments more consistent and allows us to generate better API documentation and TypeScript definition files.
I have been watching the discussions about both for some time now and figured we should get started with making improvements because I think it would be ideal from a maintenance perspective if we could generate them both instead of maintaining them manually. Therefore, I collected improvements both from the various discussions and the JSDoc documentation so the resulting output becomes more precise.
Note that this is groundwork for more documentation improvements, so more work definitely needs to be done. Thanks to the various people that discussed this and did proposals for this.
Before:
https://mozilla.github.io/pdf.js/api/draft/PDFDocumentProxy.html
After:
http://54.67.70.0:8877/15dd7d913e2aab9/api/draft/module-pdfjsLib-PDFDocumentProxy.html
(notice that all getters now have types and descriptions)